Push Notifications

The SignalWire platform can be configured to send push notifications to a subscriber that is being called. When the subscriber's device receives a push notification, it will make the device ring and forward the notification to your application. Your application should set up an audio/video link if the user accepts the call using the handlePushNotification method. The push notification is only sent if there is no active WebSocket connection to the subscriber at that moment.

Setup

To be able to receive push notifications to your applications, device-specific configurations are required.

For iOS, generate a VoIP services certificate from the Apple Developer website.

For Android, acquire the FCM API key. It can be found at the Firebase project settings under Cloud Messaging tab. To get the API key, you might have to explicitly enable "Cloud Messaging API (Legacy)".

info

There is no UI to upload the certificates for push to SignalWire yet. Please get in touch with SignalWire support who'll promptly configure your account with the certificates you want.

Handling Push Notifications

The push notification is a compressed and encrypted JSON payload which contains the caller details and the invitation that needs to be passed into the SDK to join the call.

To receive push notifications, after the app is configured with the certificates or tokens as per device requirements, the device needs to be registered using the client.registerDevice method. The registerDevice method expects a token, which the OS provides only if the user explicitly allows the app to receive push notifications.

The registerDevice method, if successful, returns a push notification decryption key, which must be saved and used to decrypt push notification messages as they are received.

Payload

Each platform has its own schema but the core message has the following attributes:

Name	Type	Description
encryption_type	string	Type of encryption used ('aes_256_gcm' or 'none')
notification_uuid	string	UUID of the push notification
with_video	string	Indicates whether the call includes video ("true" | "false")
incoming_caller_name	string	Name of the incoming caller
incoming_caller_id	string	ID of the incoming caller
invite	string	Invitation (base 64 encoded, compressed, and possibly encrypted)
title	string	Title of the call
type	string	Type of notification ('call_invite')
iv	string	The initialization vector of the encryption (base 64)
tag	string	The tag info for the encryption (base 64)
version	string	The version of the push notification received

iOS

In iOS platform devices will wrap the payload in the following structure.

Payload

{
  "aps": {
    "alert": {
      ...payload
    }
  }
}

On iOS, a special VoIP push notification will be sent which automatically invokes the system's incoming call UI.

Android and Web Notifications

Android and web platforms will wrap the payload in the following structure.

Payload

{
  "notification": {
    "body": "JSON stringified payload"
  },
  "data": {}
}

Handling the notification payload

Once the payload has been received, the invite needs to be decoded from Base64, decompressed, and decrypted using the key received during device registration. Sample implementations in React Native and for iOS are available.

Alternatively, a sample React Native project is available in the community repo.